---
title: BalanceManager
description: Learn about the balance manager and how it works.
keywords:
  [
    balancemanager,
    balance manager,
    manage balances,
    balances for different assets,
    deepbook,
    deepbookv3,
    create balance manager,
    balance manager with custom owner,
    mint trade cap,
    trade cap,
    tradecap,
    DepositCap,
    WithdrawCap,
    deposit cap,
    withdraw cap,
    deposit funds,
    withdraw funds,
    generate a TradeProof,
    tradeproof,
  ]
---

The `BalanceManager` shared object holds all balances for different assets. To perform trades, pass a combination of `BalanceManager` and `TradeProof` into a [pool](./design.mdx#pool). `TradeProof`s are generated in one of two ways, either by the `BalanceManager` owner directly, or by any `TradeCap` owner. The owner can generate a `TradeProof` without the risk of equivocation. The `TradeCap` owner, because it's an owned object, risks equivocation when generating a `TradeProof`. Generally, a high frequency trading engine trades as the default owner.

With exception to swaps, all interactions with DeepBookV3 require a `BalanceManager` as one of its inputs. When orders are matched, funds are transferred to or from the `BalanceManager`. You can use a single `BalanceManager` between all pools.

## API

Following are the different public functions that the `BalanceManager` exposes.

### Create a `BalanceManager`

The `new()` function creates a `BalanceManager`. Combine it with `share`, or else the transaction fails. You can combine the transaction with deposit calls, allowing you to create, deposit, then share the balance manager in one transaction.

<ImportContent
	source="packages/deepbook/sources/balance_manager.move"
	mode="code"
	org="MystenLabs"
	repo="deepbookv3"
	fun="new"
	noComments
/>

### Create a `BalanceManager` with custom owner

The `new_with_custom_owner()` function creates a `BalanceManager` with a custom owner. Combine it with `share`, or else the transaction fails. You can combine the transaction with deposit calls, allowing you to create, deposit, then share the balance manager in one transaction.

<ImportContent
	source="packages/deepbook/sources/balance_manager.move"
	mode="code"
	org="MystenLabs"
	repo="deepbookv3"
	fun="new_with_custom_owner"
	noComments
/>

### Create a `BalanceManager` with custom owner and capabilities

The `new_with_custom_owner_and_caps()` function creates a `BalanceManager` with a custom owner and returns all three capabilities (`DepositCap`, `WithdrawCap`, and `TradeCap`) in a single call. Combine the balance manager with `share`, or else the transaction fails. This is a convenient way to set up a complete balance manager with all necessary capabilities in one transaction.

:::caution
Move code using DeepBookV3  uses `DepositCap`, `WithdrawCap`, and `TradeCap`, while the DeepBookV3 SDK uses `depositCap`, `withdrawCap`, and `tradeCap`.
:::

<ImportContent
	source="packages/deepbook/sources/balance_manager.move"
	mode="code"
	org="MystenLabs"
	repo="deepbookv3"
	fun="new_with_custom_owner_and_caps"
	noComments
/>

### Mint a `TradeCap`

The owner of a `BalanceManager` can mint a `TradeCap` and send it to another address. Upon receipt, that address will have the capability to place orders with this `BalanceManager`. The address owner cannot deposit or withdraw funds, however. The maximum total number of `TradeCap`, `WithdrawCap`, and `DepositCap` that can be assigned for a `BalanceManager` is `1000`. If this limit is reached, one or more existing caps must be revoked before minting new ones. You can also use `revoke_trade_cap` to revoke `DepositCap` and `WithdrawCap`.

<ImportContent
	source="packages/deepbook/sources/balance_manager.move"
	mode="code"
	org="MystenLabs"
	repo="deepbookv3"
	fun="mint_trade_cap,revoke_trade_cap"
/>

### Mint a `DepositCap` or `WithdrawCap`

The owner of a `BalanceManager` can mint a `DepositCap` or `WithdrawCap` and send it to another address. Upon receipt, that address will have the capability to deposit in or withdraw from `BalanceManager`. The address owner cannot execute trades, however. The maximum total number of `TradeCap`, `WithdrawCap`, and `DepositCap` that can be assigned for a `BalanceManager` is `1000`. If this limit is reached, one or more existing caps must be revoked before minting new ones.

<ImportContent
	source="packages/deepbook/sources/balance_manager.move"
	mode="code"
	org="MystenLabs"
	repo="deepbookv3"
	fun="mint_deposit_cap,mint_withdraw_cap"
/>

### Generate a `TradeProof`

To call any function that requires a balance check or transfer, the user must provide their `BalanceManager` as well as a `TradeProof`. There are two ways to generate a trade proof, one used by the owner and another used by a `TradeCap` owner.

<ImportContent
	source="packages/deepbook/sources/balance_manager.move"
	mode="code"
	org="MystenLabs"
	repo="deepbookv3"
	fun="generate_proof_as_owner,generate_proof_as_trader"
/>

### Deposit funds

Only the owner can call this function to deposit funds into the `BalanceManager`.

<ImportContent
	source="packages/deepbook/sources/balance_manager.move"
	mode="code"
	org="MystenLabs"
	repo="deepbookv3"
	fun="deposit"
/>

### Withdraw funds

Only the owner can call this function to withdraw funds from the `BalanceManager`.

<ImportContent
	source="packages/deepbook/sources/balance_manager.move"
	mode="code"
	org="MystenLabs"
	repo="deepbookv3"
	fun="withdraw,withdraw_all"
/>

### Deposit funds using `DepositCap`

Only holders of a `DepositCap` for the `BalanceManager` can call this function to deposit funds into the `BalanceManager`.

<ImportContent
	source="packages/deepbook/sources/balance_manager.move"
	mode="code"
	org="MystenLabs"
	repo="deepbookv3"
	fun="deposit_with_cap"
/>

### Withdraw funds using `WithdrawCap`

Only holders of a `WithdrawCap` for the `BalanceManager` can call this function to withdraw funds from the `BalanceManager`.

<ImportContent
	source="packages/deepbook/sources/balance_manager.move"
	mode="code"
	org="MystenLabs"
	repo="deepbookv3"
	fun="withdraw_with_cap"
/>

### Set and unset referral

The owner of a `TradeCap` can set or unset a referral for the balance manager. Setting a referral allows the balance manager to be associated with a specific `DeepBookReferral`, which can track and earn referral fees.

<ImportContent
	source="packages/deepbook/sources/balance_manager.move"
	mode="code"
	org="MystenLabs"
	repo="deepbookv3"
	fun="set_referral,unset_referral"
/>

### Register balance manager

Register a balance manager with the registry. This adds the balance manager to the owner's list of managers in the registry.

<ImportContent
	source="packages/deepbook/sources/balance_manager.move"
	mode="code"
	org="MystenLabs"
	repo="deepbookv3"
	fun="register_manager"
/>

### Read endpoints

<ImportContent
	source="packages/deepbook/sources/balance_manager.move"
	mode="code"
	org="MystenLabs"
	repo="deepbookv3"
	fun="validate_proof,balance,owner,id,get_referral_id,referral_owner"
/>

## Related links

<RelatedLink
	href="https://github.com/MystenLabs/deepbookv3"
	label="DeepBookV3 repository"
	desc="The DeepBookV3 repository on GitHub."
/>
